perf(web): PRD-752 run web games in a worker so the page cannot stall them - #576

…baseline (PRD-752)

- check-core-boundary type-checks packages/core/src against the webworker
  lib and fails on any value read of a global a worker lacks outside
  platform.ts (red on 19 reads in 5 files, green after the move).
- platform.ts gains hostWindow/hostDocument/hostResizeObserver; audio,
  game, hot, renderer and viewport use them. The renderer now throws
  TN_RENDERER_NO_CANVAS instead of a ReferenceError with no document.
- profile:wasm-page reports main-thread busy percent.
- PRD-752 phase 1 baseline and v5 KPIs recorded; owner scope decision.

…named WebGPU failure (PRD-752)

A scratch starter booted in a worker on an OffscreenCanvas on the Wasm engine.
These are the engine-layer fixes that spike needed:

- core: defineGame takes a platform source a worker host installs
  (__tnGamePlatform) when the portable entry names none.
- core: TN_NO_RENDERER names the WebGPU failure instead of swallowing it.
- create-threenative: worker bundles get the engine resolver and ES output.
- runtime-native: the web module is built for web and worker environments.
- three-native: the renderer tolerates an OffscreenCanvas (no setAttribute).
- PRD: the spike result and the phase 3 design.

… an OffscreenCanvas (PRD-752)

serveWorkerGame (worker) and startWorkerGame (page) speak a small message
contract: a ready handshake before the canvas transfer, the platform source
the game boots on, page-relative URLs, forwarded keyboard/pointer/wheel input
in canvas coordinates, the UI bridge on its own port, and the playtest bridge
mirrored onto the page as async calls. 9 linked-pair tests.

…d (PRD-752)

A worker has no Web Audio API. The worker gets a stand-in AudioContext whose
nodes are handles; calls and property writes cross a MessagePort in one batch
per task and run on the page's real graph, so three's audio classes and
AudioBus work unchanged. AudioBus finds its gesture target in a worker, canvas
gestures reach it as they would by bubbling, and a page gesture resumes the
page's context. 7 remote-audio tests, 2 worker-host tests, 1 platform test.

… module loads (PRD-752)

The starter's game.ts calls game.ui.onIntent at top level, so in a worker the
game end connected before the page's port arrived and stayed on the in-process
broker: a blank HUD. @threenative/core/worker now installs the game end's host
globals when it loads in a worker, before the game module evaluates, and holds
frames each way until init attaches the port. 3 tests; headed GPU probe shows
the full HUD on the worker page.

src/worker.ts serves the unchanged game.ts; src/worker-page.ts keeps the
canvas, input and the same GameUi on the page. index.html stays the default,
so one build carries both arms of the busy-page A/B. Headed GPU probe: same
frame and HUD as index.html.

A worker page's requestAnimationFrame times the page, not the game. The probe
now reads frame intervals in the worker that holds the game's platform source,
else on the page, and names that thread in the result (gameThread). Main-thread
busy stays the page's CPU profile. 1 test.

…D-752)

An OffscreenCanvas cannot lock the pointer. In a worker its requestPointerLock
and exitPointerLock ask the page, which locks its own canvas within the click's
activation window and forwards each pointerlockchange with the page's verdict
as captured; a refused lock is reported as captured false. InputMap takes that
flag where no document exists, unchanged on a page. 2 tests.

A worker's requestAnimationFrame does not follow what the game presents, and
on a loaded page rAF ticks at 60 Hz while the game presents far fewer frames.
The probe now also times the game's getCurrentTexture calls (the gpuCalls
divisor) on the game's own thread, in both arms, as presented; it shims tsx's
__name in the game worker, and fails closed with a timeout. 1 test.

…sions (PRD-752)

The shooter kit gets the starter's worker page: src/worker.ts serves the
unchanged game.ts, src/worker-page.ts keeps the canvas, input and GameUi.
Headed probe on the RTX 2080: town, soldiers, rifle and the live HUD with
minimap and clock draw from the worker. The PRD logs gaps 7 to 9, the
presented-frame timing, the loaded-host rule and the measured busy share
(starter 0.9 to 1.9% on worker.html against 45.7 to 86.9% on the page).

…nner (PRD-752)

With a runner announced, the playtest plugin holds the boot until the runner
calls the bridge, so a mirror sent after start never reached the page and the
harness reported TN_PLAYTEST_BRIDGE_MISSING. The worker now posts each mirror
the moment the game installs the global. 1 test.

index.html now runs the game in a web worker; main.html is the named override
that runs it on the page thread. The worker canvas forwards setAttribute to the
page canvas, so the harness reads the renderer's data-engine for capture
provenance (was TN_PLAYTEST_CAPTURE_PROVENANCE_MISSING). 1 test.

Mesh::raycast tested every triangle of the mesh. The shooter's merged town
meshes hold about 430k triangles, so a few soldier line-of-sight rays cost
about 90 ms in one update, which was the stutter left on the worker page.
The tree is built on first use, rebuilt when positions, index or drawRange
change, and skipped for morphed meshes and meshes that pose their vertices
(SkinnedMesh). Candidates run the unchanged hit code in triangle order, so
results stay identical: 2,048 oracle rays, 0 differ. 1,000 rays on a 20k
mesh: 8,471 ms -> 6.0 ms; a focused ray tests 4 of 20,000 triangles.

… and profiler (PRD-752)

Worker: startup errors reject ready, stop removes the canvas and releases
pointer lock and capture, pointerlockerror, 0x0 clamp, HUD wheel stays on
the HUD, motion coalesced per page frame, one HUD snapshot in flight,
gamepads forwarded, a lazy playtest mirror with _clockEpoch.
Audio: the clock freezes while suspended, fluent AudioParam calls reuse
their handle, ended one-shots release theirs, numeric param defaults,
control ops settle from the page. Profiler: probes run in the game realm.
Each item has a red-green spec.

… A/Bs (PRD-752)

The default flags unthrottle the page's requestAnimationFrame, not a worker's
OffscreenCanvas frames, so a worker arm read 37 ms frames against 10 ms on the
page. With vsync on, the shooter worker ran 16.7 ms frames against 33.3 ms on
the page thread. Also types the memory probe's realm (Page | Worker union).

…PRD-752)

Under a private Xvfb the runner adds --disable-frame-rate-limit so a page
game's frames escape the compositor's cadence. The same flag throttles a
worker's OffscreenCanvas frames (shooter: 36 ms presented with it, 16.7 ms
without). The runner now sees a worker game once the page opens and relaunches
once with that thread's flags; the report says gameThread: worker.

…sion (PRD-752)

…quests (PRD-752)

A wall-clock advance answers a one-tick request with the ticks the host's pump
ran: two per frame at 30 fps on a 60 Hz step. advanceFixedStep counted
requests, so a 169-tick key hold ran about 338 ticks and the starter's player
overshot into the gap on the worker page. The bridge client now returns the
reported count and the loop counts it; a fixed-step bridge still runs exactly
one tick per request. Starter play passes on / (worker) and /main.html.

…ock hold decisions

…call evidence)

… splittable engine work)

…pool waits on PRD-573 v3.1